Node / meshtastic / Meshtastic-Android / files / docs / README.md

Displaying Raw • View rendered • Download

Tc9d1d9# Documentation Structure

This directory contains the source documentation for the Meshtastic Android/Desktop/iOS app.

It serves three consumers:

Tff7b721. **In-app docs browser** — bundled via Compose Resources at build time

Tff7b722. **Jekyll site** — GitHub Pages (this directory is the Jekyll source root)

Tff7b723. **meshtastic.org** — Docusaurus sync (upstream consumption)

Tc9d1d9## Locale Layout

Ta5d6ff```

docs/

├── _config.yml, _data/, _layouts/, _sass/ ← Jekyll site infrastructure

├── en/ ← English source (edit here)

│ ├── user/ ← User Guide pages

│ ├── developer/ ← Developer Guide pages

│ ├── index.md ← Site home page

│ ├── user.md ← User Guide nav parent

│ └── developer.md ← Developer Guide nav parent

├── fr-rFR/ ← French (Crowdin-generated)

│ └── user/ ← Translated user guide

├── de-rDE/ ← German (Crowdin-generated)

│ └── user/

└── ... ← Other locales

```

Tc9d1d9## Editing Guidelines

Tff7b72- **English source**: Edit files under Ta5d6ff`docs/en/`. These are the authoritative source.

Tff7b72- **Translations**: Do **not** edit files in locale folders directly. They are auto-generated

by [Tff7b72Crowdin](Te6edf3https://crowdin.com/project/meshtastic-android) and will be overwritten on sync.

Contribute translations via Crowdin instead.

Tff7b72- **Adding a page**: Create the Ta5d6ff`.md` file in Ta5d6ff`docs/en/user/` or Ta5d6ff`docs/en/developer/`, then

register it in Ta5d6ff`feature/docs/.../DocBundleLoader.kt` for in-app bundling.

Tc9d1d9## How Translations Work

Tff7b721. English source files (Ta5d6ff`docs/en/user/*.md`) are uploaded to Crowdin as translation sources

Tff7b722. Volunteers translate via the Crowdin web UI

Tff7b723. Crowdin PRs land translated files at Ta5d6ff`docs/{android_code}/user/*.md` (e.g., Ta5d6ff`fr-rFR`, Ta5d6ff`pt-rBR`)

Tff7b724. At build time, the Gradle Ta5d6ff`syncTranslatedDocsToComposeResources` task bundles them into

locale-qualified Compose Resources for the in-app reader

Tff7b725. The in-app Ta5d6ff`DocBundleLoader` tries the user's locale first, then falls back to English

Tc9d1d9## Publishing & Versioning

The GitHub Pages site is published to the persistent Ta5d6ff`gh-pages` branch as parallel

channels (GitHub Pages must be configured to serve from that branch):

| Path | Content | Published by |

|------|---------|--------------|

| Ta5d6ff`/` | Latest production release (default landing) | Ta5d6ff`docs-release.yml` on Ta5d6ff`vX.Y.Z` tags |

| Ta5d6ff`/vX.Y.Z/` | Permanent per-release copy | Ta5d6ff`docs-release.yml` on Ta5d6ff`vX.Y.Z` tags |

| Ta5d6ff`/vX.Y.Z-open.N/` | Per-tag open-testing snapshot | Ta5d6ff`docs-release.yml` on Ta5d6ff`vX.Y.Z-open.N` tags |

| Ta5d6ff`/vX.Y.Z-closed.N/` | Per-tag closed-testing snapshot | Ta5d6ff`docs-release.yml` on Ta5d6ff`vX.Y.Z-closed.N` tags |

| Ta5d6ff`/main/` | Snapshot of the Ta5d6ff`main` branch | Ta5d6ff`docs-deploy.yml` on pushes to Ta5d6ff`main` |

| Ta5d6ff`/api/` | Dokka API reference | Ta5d6ff`docs-deploy.yml`, plus production releases |

| Ta5d6ff`/versions.json` | Version manifest for the site's version switcher | regenerated on every deploy |

Ta5d6ff`-internal.N` tags are deliberately not published — they are cut many times per

cycle and are not a documented channel.

Prerelease snapshots accumulate during a version cycle so testers can read the

docs for the exact build they are running. Once the production Ta5d6ff`vX.Y.Z` tag

ships, Ta5d6ff`/vX.Y.Z/` supersedes them and **Post-Release Cleanup** (run with

Ta5d6ff`base_version=X.Y.Z`) reaps the Ta5d6ff`vX.Y.Z-open.*` / Ta5d6ff`vX.Y.Z-closed.*` directories

along with the prerelease tags. That workflow defaults to a dry run.

Only production releases own Ta5d6ff`/` and rebuild Ta5d6ff`/api/`. Prerelease tags publish

their own directory only: Ta5d6ff`/api/` is unversioned and already refreshed by every

push to Ta5d6ff`main`, so rebuilding Dokka (~14 min) per prerelease tag would cost far

more than it refreshes. Until a production release exists, Ta5d6ff`/` redirects to the

best available channel — newest open, then newest closed, then Ta5d6ff`/main/` — and

upgrades automatically as better channels appear. Real release content at the

root is never overwritten by that fallback.

Each deploy overlays only its own channels via Ta5d6ff`scripts/docs/publish-to-gh-pages.sh`,

so release history accumulates instead of being wiped by the next deploy. The header

version dropdown (Ta5d6ff`_includes/version_switcher.html`) reads Ta5d6ff`/versions.json` at runtime;

a separate header link points to the upstream docs at meshtastic.org. To backfill a

release (e.g. after first enabling this), run the "Docs Release" workflow manually

against the release tag.